home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Extra 1997 #2 / Amiga Plus Extra 1997 #2.iso / system / mui / developer / autodocs / mui_dataspace.doc < prev    next >
Encoding:
Text File  |  1997-02-16  |  5.4 KB  |  216 lines
  1. TABLE OF CONTENTS
  2.  
  3. Dataspace.mui/Dataspace.mui
  4. Dataspace.mui/MUIA_Dataspace_Pool
  5. Dataspace.mui/MUIM_Dataspace_Add
  6. Dataspace.mui/MUIM_Dataspace_Clear
  7. Dataspace.mui/MUIM_Dataspace_Find
  8. Dataspace.mui/MUIM_Dataspace_Merge
  9. Dataspace.mui/MUIM_Dataspace_ReadIFF
  10. Dataspace.mui/MUIM_Dataspace_Remove
  11. Dataspace.mui/MUIM_Dataspace_WriteIFF
  12. Dataspace.mui/Dataspace.mui
  13.  
  14.     The Dataspace class serves as a very simple container for
  15.     all kinds of data. You can add data items and reference them
  16.     later through an ID. Furthermore, Dataspace class features
  17.     methods to import/export a complete Dataspace from/to an IFF
  18.     file handle.
  19.  
  20.     MUI uses subclasses of dataspace class to handle all its
  21.     configuration data and thats probably the main purpose of a
  22.     dataspace.
  23. Dataspace.mui/MUIA_Dataspace_Pool
  24.  
  25.     NAME
  26.     MUIA_Dataspace_Pool -- (V11) [I..], APTR
  27.  
  28.     FUNCTION
  29.     If you specify a memory pool from exec.library/CreatePool()
  30.     here, the dataspace object will use this pool for all its
  31.     entries.
  32.  
  33.     If you omit this tag or pass NULL, the dataspace object
  34.     will create its own memory pool instead.
  35.  
  36.     SEE ALSO
  37.     MUIM_Dataspace_Add, exec.library/CreatePool
  38. Dataspace.mui/MUIM_Dataspace_Add
  39.  
  40.     NAME
  41.     MUIM_Dataspace_Add (V11)
  42.  
  43.     SYNOPSIS
  44.     DoMethod(obj,MUIM_Dataspace_Add,APTR data, LONG len, ULONG id);
  45.  
  46.    FUNCTION
  47.     This method adds a new entry to the dataspace. If an entry
  48.     with the same ID already exists, it will be replaced with
  49.     the new entry.
  50.  
  51.     INPUTS
  52.     data - pointer to a data
  53.     len  - length of data
  54.     id   - reference id
  55.  
  56.     RESULT
  57.     Returns NULL on failure (probably because of a memory
  58.     shortage) or some non NULL value on success.
  59.  
  60.     SEE ALSO
  61.     MUIM_Dataspace_Remove, MUIM_Dataspace_Find
  62. Dataspace.mui/MUIM_Dataspace_Clear
  63.  
  64.     NAME
  65.     MUIM_Dataspace_Clear (V11)
  66.  
  67.     SYNOPSIS
  68.     DoMethod(obj,MUIM_Dataspace_Clear,);
  69.  
  70.    FUNCTION
  71.     This method clears all the contents of a dataspace. Depending
  72.     on the state of the memory pool that the dataspace object uses,
  73.     this may or may not result in more free memory.
  74.  
  75.     INPUTS
  76.     none
  77.  
  78.     RESULT
  79.     All entries will be removed from the dataspace.
  80.     The return value of this method is currently undefined.
  81.  
  82.     SEE ALSO
  83.     MUIM_Dataspace_Add, MUIM_Dataspace_Remove,
  84.     MUIM_Dataspace_Merge
  85. Dataspace.mui/MUIM_Dataspace_Find
  86.  
  87.     NAME
  88.     MUIM_Dataspace_Find (V11)
  89.  
  90.     SYNOPSIS
  91.     DoMethod(obj,MUIM_Dataspace_Find,ULONG id);
  92.  
  93.     FUNCTION
  94.     yet undocumented, complain in the beta mailing list :)
  95.  
  96.     INPUTS
  97.  
  98.     RESULT
  99.  
  100.     BUGS
  101.  
  102.     SEE ALSO
  103.  
  104. Dataspace.mui/MUIM_Dataspace_Merge
  105.  
  106.     NAME
  107.     MUIM_Dataspace_Merge (V11)
  108.  
  109.     SYNOPSIS
  110.     DoMethod(obj,MUIM_Dataspace_Merge,Object *dataspace);
  111.  
  112.    FUNCTION
  113.     This method adds all the contents of the merge dataspace
  114.     specified as parameter to the objects dataspace.
  115.     As with MUIM_Dataspace_Add, entries with equal IDs
  116.         will be replaced.
  117.  
  118.     INPUTS
  119.     dataspace - dataspace objects whichs contents should
  120.                 be merged.
  121.  
  122.     RESULT
  123.     Returns the number of entries that have been
  124.     added/replaced in the objects dataspace. If this
  125.     number doesnt match the number of entries in the
  126.     merge dataspace, something probably went wrong.
  127.  
  128.     SEE ALSO
  129.     MUIM_Dataspace_Add, MUIM_Dataspace_Remove
  130. Dataspace.mui/MUIM_Dataspace_ReadIFF
  131.  
  132.     NAME
  133.     MUIM_Dataspace_ReadIFF (V11)
  134.  
  135.     SYNOPSIS
  136.     DoMethod(obj,MUIM_Dataspace_ReadIFF,struct IFFHandle *handle);
  137.  
  138.     FUNCTION
  139.     Adds the contents of an IFF handle from iffparse.library to
  140.     the dataspace. As always, objects with the same ID that
  141.     are already in the dataspace will be replaced.
  142.  
  143.     This method does not look for any chunk types and chunk ids
  144.     itself. Instead, it expects that you have already located
  145.     the chunk which contains your data and does nothing
  146.     but ReadChunkBytes() until all dataspace entries of
  147.     the current chunk are read.
  148.  
  149.     NOTES
  150.     Do not call MUIM_Dataspace_ReadIFF if your handle is
  151.     positioned on chunks that were not written with 
  152.     MUIM_Dataspace_WriteIFF or strange things may happen!
  153.  
  154.     INPUTS
  155.     handle - pointer to a struct IFFHandle from
  156.              iffparse.library/AllocIFF(). The handle must
  157.              already be open, initialized for reading and
  158.              positioned on a chunk that was created with
  159.              MUIM_Dataspace_WriteIFF.
  160.  
  161.     RESULT
  162.     Returns 0 on success or some IFFERR_xxx on failure.
  163.  
  164.     SEE ALSO
  165.     MUIM_Dataspace_ReadIFF, iffparse.library/AllocIFF
  166. Dataspace.mui/MUIM_Dataspace_Remove
  167.  
  168.     NAME
  169.     MUIM_Dataspace_Remove (V11)
  170.  
  171.     SYNOPSIS
  172.     DoMethod(obj,MUIM_Dataspace_Remove,ULONG id);
  173.  
  174.    FUNCTION
  175.     This method removes an entry from the dataspace.
  176.  
  177.     INPUTS
  178.     id - reference id
  179.  
  180.     RESULT
  181.     Returns NULL if no entry with the given ID was found
  182.     in the dataspace or some non NULL value on success.
  183.  
  184.     SEE ALSO
  185.     MUIM_Dataspace_Add, MUIM_Dataspace_Find
  186. Dataspace.mui/MUIM_Dataspace_WriteIFF
  187.  
  188.     NAME
  189.     MUIM_Dataspace_WriteIFF (V11)
  190.  
  191.     SYNOPSIS
  192.     DoMethod(obj,MUIM_Dataspace_WriteIFF,struct IFFHandle *handle, ULONG type, ULONG id);
  193.  
  194.     FUNCTION
  195.     Writes the contents of a dataspace to an IFF handle of
  196.     iffparse.library.
  197.  
  198.     In detail, a chunk with the specified type and id is created
  199.     with PushChunk(), the contents of the dataspace are written
  200.     with WriteChunkBytes() and the chunk is terminated with
  201.     PopChunk().
  202.  
  203.     INPUTS
  204.     handle - pointer to a struct IFFHandle from
  205.              iffparse.library/AllocIFF(). The handle must
  206.              already be open and initialized for writing.
  207.  
  208.     type   - type of chunk to create
  209.     id     - id of chunk to create
  210.  
  211.     RESULT
  212.     Returns 0 on success or some IFFERR_xxx on failure.
  213.  
  214.     SEE ALSO
  215.     MUIM_Dataspace_ReadIFF, iffparse.library/AllocIFF
  216.